/*
 * Copyright 2011 LMAX Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.lmax.disruptor;


/**
 * [ANALYSIS] Disruptor等待策略接口 - 控制消费者等待新事件的核心抽象
 * 
 * [DESIGN] 设计目标：
 * 为EventProcessor提供可插拔的等待机制，支持不同场景下的性能权衡
 * 通过策略模式将等待逻辑与事件处理逻辑解耦，提供灵活的性能调优能力
 * 
 * [STRATEGY] 主要实现策略：
 * - BlockingWaitStrategy: 基于锁的阻塞等待，低CPU占用，适合低频场景
 * - YieldingWaitStrategy: 先忙等待后让出CPU，平衡性能和资源消耗
 * - BusySpinWaitStrategy: 纯忙等待，极低延迟但100% CPU占用
 * - SleepingWaitStrategy: 渐进式等待，在延迟和CPU之间找到最佳平衡
 * 
 * [PERFORMANCE] 性能特征对比：
 * 延迟排序: BusySpinWaitStrategy < YieldingWaitStrategy < SleepingWaitStrategy < BlockingWaitStrategy
 * CPU消耗: BusySpinWaitStrategy > YieldingWaitStrategy > SleepingWaitStrategy > BlockingWaitStrategy
 * 
 * [USAGE] 使用场景指导：
 * - 高频交易、实时系统: BusySpinWaitStrategy
 * - 中频处理、平衡场景: YieldingWaitStrategy或SleepingWaitStrategy  
 * - 低频处理、资源受限: BlockingWaitStrategy
 * 
 * [COORDINATION] 协调机制：
 * 与生产者的序列号发布机制协调，通过cursor序列号的更新来唤醒等待的消费者
 * 支持多消费者场景下的dependentSequence依赖关系管理
 * 
 * @see EventProcessor 事件处理器，使用等待策略来等待新事件
 * @see SequenceBarrier 序列号屏障，封装等待策略的具体使用
 * @see Sequence 序列号，等待策略监控的核心状态
 */
public interface WaitStrategy
{
    /**
     * [WORKFLOW] 等待指定序列号变为可用 - 消费者获取新事件的核心等待机制
     * 
     * [ALGORITHM] 等待逻辑：
     * 1. 检查目标序列号是否已经可用（通过dependentSequence比较）
     * 2. 如果不可用，根据具体策略执行等待逻辑：
     *    - BlockingWaitStrategy: 在mutex上阻塞等待
     *    - YieldingWaitStrategy: 先忙等待100次，然后Thread.yield()
     *    - BusySpinWaitStrategy: 纯忙等待循环
     *    - SleepingWaitStrategy: 渐进式等待（忙等->yield->sleep）
     * 3. 定期检查SequenceBarrier的alert状态，支持优雅停机
     * 4. 返回实际可用的最大序列号（可能大于请求的序列号）
     * 
     * [CONCURRENCY] 并发协调：
     * - cursor: RingBuffer的主序列号，生产者发布时会更新此值
     * - dependentSequence: 当前消费者依赖的序列号，通常是前置消费者的进度
     * - barrier: 序列号屏障，提供alert机制和依赖关系管理
     * 
     * [PERFORMANCE] 性能考虑：
     * - 返回值可能大于请求序列号，支持批量处理优化
     * - 不同策略在延迟、CPU占用、上下文切换之间做出不同权衡
     * - 支持超时机制，某些策略可以返回小于请求序列号的值表示超时
     * 
     * [EXCEPTION] 异常处理：
     * - AlertException: Disruptor状态改变（如停机），需要立即退出等待
     * - InterruptedException: 线程被中断，需要响应中断信号
     * - TimeoutException: 等待超时，某些策略支持超时控制
     * 
     * [PATTERN] 使用模式：
     * 通常由BatchEventProcessor在主循环中调用：
     * <pre>{@code
     * long nextSequence = sequence + 1;
     * long availableSequence = barrier.waitFor(nextSequence);
     * while (nextSequence <= availableSequence) {
     *     // 处理sequence为nextSequence的事件
     *     nextSequence++;
     * }
     * }</pre>
     *
     * @param sequence 期望等待的序列号，消费者希望处理的下一个事件序列号
     * @param cursor RingBuffer的主游标序列号，生产者发布事件时会更新
     * @param dependentSequence 依赖的序列号，确保事件处理的顺序性
     * @param barrier 序列号屏障，提供alert检查和依赖管理功能
     * @return 实际可用的序列号，可能等于或大于请求的序列号，支持批量处理
     * @throws AlertException 当Disruptor状态发生变化时抛出，需要立即停止等待
     * @throws InterruptedException 当线程被中断时抛出，需要响应中断信号
     * @throws TimeoutException 当等待超时时抛出（部分策略支持）
     */
    long waitFor(long sequence, Sequence cursor, Sequence dependentSequence, SequenceBarrier barrier)
        throws AlertException, InterruptedException, TimeoutException;

    /**
     * [WORKFLOW] 通知所有等待的EventProcessor游标已前进 - 生产者发布事件后的消费者唤醒机制
     * 
     * [ALGORITHM] 通知逻辑：
     * 当生产者通过publish()方法发布事件后，会调用此方法来唤醒可能正在等待的消费者
     * 不同等待策略的实现方式：
     * - BlockingWaitStrategy: 通过synchronized + notifyAll()唤醒阻塞在mutex上的线程
     * - YieldingWaitStrategy: 空实现，因为消费者在主动轮询，无需唤醒
     * - BusySpinWaitStrategy: 空实现，因为消费者在忙等待中，无需唤醒
     * - SleepingWaitStrategy: 空实现，消费者会通过超时自动醒来
     * 
     * [CONCURRENCY] 并发协调：
     * - 调用时机：由Sequencer在publish()方法中调用
     * - 线程安全：实现必须是线程安全的，支持多生产者场景
     * - 性能考虑：只有BlockingWaitStrategy需要实际的唤醒操作，其他策略为空实现
     * 
     * [DESIGN] 设计考虑：
     * - 策略模式：不同等待策略有不同的唤醒需求，通过接口统一抽象
     * - 性能优化：只在需要时才进行实际的唤醒操作，避免不必要的系统调用
     * - 解耦设计：生产者不需要知道具体的等待策略，通过统一接口进行通知
     * 
     * [PERFORMANCE] 性能特征：
     * - BlockingWaitStrategy: 需要获取锁并调用notifyAll()，有一定开销
     * - 其他策略: 空方法调用，几乎无开销
     * - 调用频率: 每次事件发布都会调用，需要高效实现
     * 
     * [COORDINATION] 与其他组件协调：
     * - Sequencer.publish(): 发布序列号后调用此方法
     * - EventProcessor.waitFor(): 可能被此方法唤醒
     * - SequenceBarrier: 作为中介，连接等待策略和事件处理器
     * 
     * @see Sequencer#publish(long) 发布序列号时会调用此方法
     * @see EventProcessor#run() 事件处理器主循环，可能被此方法唤醒
     * @see BlockingWaitStrategy#signalAllWhenBlocking() 唯一需要实际唤醒操作的实现
     */
    void signalAllWhenBlocking();
}
